Overview
Auth
- POSTCreate a new API key for the authenticated tenant.
- GETList all API keys for the authenticated tenant.
- GETGet details of a specific API key.
- POSTRotate an API key. Creates a new key and revokes the old one.
- DELRevoke an API key. The key is immediately invalidated.
- GETList the browser origins allow-listed for this API key.
- PUTReplace the browser origin allow-list for this API key.
- GETGet information about the authenticated tenant.
- PATCHUpdate tenant information (name).
- GETList audit log entries for the authenticated tenant.
- POSTCreate a Stripe Checkout session for tenant provisioning.
- GETRetrieve a provisioned API key after Stripe Checkout. The claim token (checkout session ID) acts as the access credential. One-time retrieval only — the key cannot be shown again.
Contacts
- GETList contacts with optional filtering by kind, search query, and pagination.
- POSTCreate a new contact.
- GETGet a contact by ID.
- PUTUpdate a contact.
- DELSoft-delete a contact.
- GETFind a contact by communication channel (type + value).
- POSTAdd a communication channel to a contact.
- DELRemove a communication channel from a contact.
- POSTAdd a postal address to a contact.
- PUTUpdate a postal address.
- DELRemove a postal address from a contact.
- POSTAdd a significant date to a contact (birthday, anniversary, etc.).
- PUTUpdate a significant date.
- DELRemove a significant date from a contact.
- GETList relationships for a contact.
- POSTAdd a relationship between two contacts.
- DELRemove a relationship.
- GETList organizational affiliations for a contact.
- POSTAdd an organizational affiliation to a contact.
- DELRemove an organizational affiliation.
- GETList interactions for a contact.
- POSTLog an interaction with a contact.
- POSTAdd a tag to a contact.
- DELRemove a tag from a contact.
- GETList all contact tag definitions for the tenant.
- POSTCreate a new contact tag definition.
- GETList all contact groups for the tenant.
- POSTCreate a new contact group.
- DELDelete a contact group.
- GETList members of a contact group.
- POSTAdd a contact to a group.
- DELRemove a contact from a group.
- GETList all relationship types for the tenant.
CRM
- GETList all CRM pipelines with their stages.
- POSTCreate a new pipeline, optionally with initial stages.
- GETGet a pipeline by ID with its stages.
- PUTUpdate a pipeline.
- DELDelete a pipeline (soft delete).
- POSTSet a pipeline as the default.
- GETList stages in a pipeline.
- POSTCreate a new stage in a pipeline.
- PUTReorder stages in a pipeline.
- PUTUpdate a stage.
- DELDelete a stage from a pipeline.
- GETGet a pipeline summary with deal counts and values per stage.
- GETList deals with optional filtering.
- POSTCreate a new deal.
- GETGet a deal by ID.
- PUTUpdate a deal.
- DELDelete a deal (soft delete).
- POSTMove a deal to a different stage. Records a stage change audit entry.
- GETGet stage change history for a deal.
- GETList contacts associated with a deal.
- POSTAssociate a contact with a deal.
- DELRemove a contact from a deal.
- POSTAdd a tag to a deal.
- DELRemove a tag from a deal.
- GETList all CRM tag definitions.
- POSTCreate a new CRM tag definition.
Tasks
- GETList projects with optional filtering.
- POSTCreate a new project.
- GETGet a project by ID with statuses, sections, milestones, and counts.
- PUTUpdate a project.
- DELDelete a project (soft delete).
- GETList custom statuses for a project.
- POSTAdd a custom status to a project.
- PUTUpdate a project status.
- DELRemove a status from a project.
- GETList sections in a project.
- POSTAdd a section to a project.
- PUTUpdate a project section.
- DELRemove a section from a project.
- GETList milestones in a project.
- POSTAdd a milestone to a project.
- PUTUpdate a milestone.
- DELRemove a milestone.
- GETList members of a project.
- POSTAdd a member to a project.
- DELRemove a member from a project.
- GETList tasks with optional filtering.
- POSTCreate a new task.
- GETGet a task by ID.
- PUTUpdate a task.
- DELDelete a task (soft delete).
- GETGet a task by its human-readable identifier (e.g., PROJ-42).
- GETList overdue tasks.
- POSTMark a task as complete.
- POSTCancel a task.
- GETList subtasks of a task.
- GETList dependencies of a task.
- POSTAdd a dependency to a task.
- DELRemove a dependency from a task.
- GETList comments on a task.
- POSTAdd a comment to a task.
- PUTUpdate a task comment.
- POSTAdd a label to a task.
- DELRemove a label from a task.
- GETList cross-domain links for a task.
- POSTAdd a cross-domain link to a task.
- DELRemove a cross-domain link from a task.
- PATCHReprioritize a task by placing it between two neighbors. Cascades to dependent tasks (`blocked_by` pushed below, `blocks` pushed above) so dependency ordering invariants stay intact. Returns the new priority key plus any cascaded entries. See `docs/tasks/priority-cascade.md`.
- GETList all task label definitions for the tenant.
- POSTCreate a new task label definition.
Calendar
- GETList calendars for the authenticated tenant.
- POSTCreate a new calendar.
- GETGet a calendar by ID.
- PUTUpdate a calendar.
- DELDelete a calendar (soft delete).
- GETList events with optional filtering by date range, calendar, and type.
- POSTCreate a new event.
- GETGet an event by ID with attendees and links.
- PUTUpdate an event.
- DELDelete an event (soft delete).
- GETFull-text search across events.
- POSTAdd an attendee to an event.
- PUTUpdate an attendee's RSVP status.
- DELRemove an attendee from an event.
- POSTAdd a cross-domain link to an event.
- DELRemove a cross-domain link from an event.
Notes
- GETList all notebooks for the tenant with note counts.
- POSTCreate a new notebook.
- GETGet a notebook by ID with note count.
- PUTUpdate a notebook.
- DELDelete a notebook (soft delete).
- GETList notes with optional filtering by notebook, tag, and search.
- POSTCreate a new note.
- GETGet a note by ID.
- PUTUpdate a note.
- DELDelete a note (soft delete).
- GETList outgoing links from a note.
- POSTAdd a link from a note to another entity.
- DELRemove a link from a note.
- GETList notes that link to a given note (backlinks).
- GETList notes that link to any entity (cross-domain backlinks).
- POSTAdd a tag to a note (creates the tag if it does not exist).
- DELRemove a tag from a note.
- GETList attachments for a note.
- POSTAdd an attachment to a note.
- DELRemove an attachment from a note.
- GETList all note tag definitions for the tenant.
- POSTCreate a new note tag definition.
Members
- POSTCreate a new member within the tenant.
- GETList all members for the tenant.
- GETGet the authenticated member's own information.
- GETGet a member by ID.
- PATCHUpdate a member (name, email, role, active status, metadata).
- DELDeactivate a member (soft disable — sets is_active = false).
- PUTReplace all access policies for a member (PUT semantics).
- GETGet all access policies for a member.
- POSTCreate an API key linked to a specific member.
- POSTCreate an invitation for a new member.
- GETList all invitations for the tenant.
- DELRevoke a pending invitation.
- POSTClaim an invitation using a claim code. Public endpoint — no auth required. Returns the newly created member, an API key, and access policies.
Agents
- GETList all `agent_configs` rows for the current tenant.
- GETGet a single `agent_configs` row by blueprint.
- PUTUpsert the non-BYOK portion of an `agent_configs` row. Full-replace semantics — omitted fields revert to NULL / `[]`.
- DELDelete an `agent_configs` row. Does not cascade to `agent_runs` — historical run rows remain queryable.
- POSTProbe a candidate API key against Anthropic without persisting it. Used by the wizard path: the frontend validates a key before the user commits it. Always returns 200 — the `ProbeResult` body distinguishes valid from invalid.
- PUTSet (or rotate) the BYOK key for one agent blueprint. Orchestrates the probe → encrypt → store sequence in a single atomic call so a client that skips `validate-key` still gets a safe error on bad input.
- DELOperator revoke: wipes the ciphertext and pins `byok_status` to `revoked`. Sticky per the state machine — the tenant must re-enter a key (via `PUT /byok-key`) to return to active.
- GETList runs for an agent blueprint with cursor pagination and optional status filter. Newest-first.
- POSTEnqueue a new agent run. Returns the inserted row; the worker wakes via `NOTIFY agent_runs_new` (fired by the schema trigger on commit).
- GETFetch one run plus its journal steps (in seq order).
- POSTCancel a non-terminal run. No-op on already-terminal runs (returns 409).
- GETGet apiv1agent schedules
- POSTPost apiv1agent schedules
- GETGet apiv1agent schedules
- PUTPut apiv1agent schedules
- DELDelete apiv1agent schedules
- POSTPost apiv1agent schedules enable
- POSTPost apiv1agent schedules disable
- POSTStore (or replace) a service credential for a provider.
- GETList all integration keys for the current tenant (any status, masked).
- GETGet the active or invalid integration key for one provider (masked).
- DELRevoke (disconnect) an integration key. Wipes the ciphertext and sets status to `revoked`. Returns 404 if no active or invalid key exists.
- POSTProbe the stored credential against the provider's API. Updates `status` and `last_verified_at`. Returns 404 if no key is stored or if the key is already revoked.
Apps
- POSTRegister a new app. Validates URL (SSRF), encrypts auth, inserts row, probes immediately. Probe failures do NOT fail registration — the row persists with `status='unhealthy'`, and the probe outcome is reflected in the response body.
- GETList all apps for the current tenant, most recently registered first.
- GETGet one app by slug.
- PATCHPatch display_name, description, enabled_tools, status (active|disabled), metadata. Slug and mcp_server_url are immutable (rename = delete + register).
- DELHard-delete the app connection. Returns 204.
- POSTReplace the stored auth secret. Writes new encrypted value + hint, bumps `key_version`. Does NOT trigger a probe — call `/probe` after to verify.
- POSTOn-demand probe. Refreshes the tool manifest and health status. Always returns 200 — probe failures are reported in the body, not the status code.
Webhooks
- GETList all webhook endpoints.
- POSTCreate a new webhook endpoint. Returns signing secret once.
- GETGet a webhook endpoint by ID. Does not include signing secret.
- PUTUpdate a webhook endpoint.
- DELSoft-delete a webhook endpoint.
- POSTSend a test ping event to a webhook endpoint. Uses the same pinned-DNS + dual-sign + capped-body code path as the delivery worker so a successful test is a faithful dry run of production delivery.
- POSTRotate the signing secret for a webhook endpoint. Returns new secret once.
- GETList recent webhook events.
- GETGet a webhook event by ID with payload.
- POSTRetry delivery of a specific event to all matching active endpoints.
- POSTBulk recover failed events from a timestamp.
Billing & Usage
Self-Service
- GETUnified integrations list across `integration_keys`, `oauth_connections`, and `agent_configs` (BYOK rows).
- DELRevoke one integration by `(kind, id)`. Dispatches to the existing per-kind revoke helper:
- GETList recent digest deliveries for the authenticated tenant. Returns the last 30 days, newest first, capped at 100 rows.
OAuth
- POST`POST /api/v1/oauth/google/authorize`
- GET`GET /api/v1/oauth/google/callback?code=...&state=...`
- GETList OAuth connections for the current tenant.
- GETGet one OAuth connection (masked — no ciphertext, no decryption).
- DELRevoke an OAuth connection. Best-effort upstream revoke, then wipe ciphertext and flip to `revoked`. The row is retained for audit.
- POSTProbe the stored connection by loading the credential (triggers refresh if expiring). Always returns 200 with a `valid: bool` body — a failed probe doesn't map to 4xx so the dashboard can render the reason.
Admin
- GETList activity log entries with filtering + cursor pagination.
- GETGet a single activity log entry by id. Cross-tenant returns 404.
- POSTMark an activity log entry as acknowledged. Re-ack is idempotent — `acknowledged_at` stays at the first ack timestamp; `acknowledged_by` updates to the most recent ack actor.
- GETAggregate `agent_runs` over a time window.
- POSTForce a fresh delivery attempt for a note. Admin-only. Creates a new pending row with `attempt_of` pointing at the most recent delivery on record for that note.
Upsert the non-BYOK portion of an `agent_configs` row. Full-replace
semantics — omitted fields revert to NULL / `[]`.
curl --request PUT \
--url https://api.worktruck.app/api/v1/agent-configs/{blueprint} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"budget_default_cents": 123,
"deadline_default_seconds": 123,
"guardrails": "<unknown>",
"schedule": "<string>"
}
'{
"agent_blueprint": "<string>",
"byok_status": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"guardrails": "<unknown>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"updated_at": "2023-11-07T05:31:56Z",
"budget_default_cents": 123,
"byok_last_probed_at": "2023-11-07T05:31:56Z",
"byok_status_reason": "<string>",
"deadline_default_seconds": 123,
"schedule": "<string>"
}Agents
Upsert the non-BYOK portion of an `agent_configs` row. Full-replace semantics — omitted fields revert to NULL / `[]`.
PUT
/
api
/
v1
/
agent-configs
/
{blueprint}
Upsert the non-BYOK portion of an `agent_configs` row. Full-replace
semantics — omitted fields revert to NULL / `[]`.
curl --request PUT \
--url https://api.worktruck.app/api/v1/agent-configs/{blueprint} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"budget_default_cents": 123,
"deadline_default_seconds": 123,
"guardrails": "<unknown>",
"schedule": "<string>"
}
'{
"agent_blueprint": "<string>",
"byok_status": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"guardrails": "<unknown>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"updated_at": "2023-11-07T05:31:56Z",
"budget_default_cents": 123,
"byok_last_probed_at": "2023-11-07T05:31:56Z",
"byok_status_reason": "<string>",
"deadline_default_seconds": 123,
"schedule": "<string>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Agent blueprint identifier
Body
application/json
Request body for PUT /agent-configs/{blueprint}. Full-replace semantics —
any field omitted from the body reverts to NULL / []. BYOK key entry
is a separate endpoint (PUT /agent-configs/{blueprint}/byok-key) so raw
secrets never flow through the generic upsert path.
Default budget cap in USD cents for a run enqueued under this kind.
Default wall-clock deadline in seconds from run start.
JSON array of guardrail rule primitives. Defaults to [] if omitted.
Cron expression (5-field POSIX, extended with seconds optional).
Response
Config upserted
A single agent_configs row as exposed over the REST API. Deliberately
omits byok_key_ref and byok_key_version — those never cross the
API boundary.
Was this page helpful?
Get a single `agent_configs` row by blueprint.Delete an `agent_configs` row. Does not cascade to `agent_runs` —
historical run rows remain queryable.
⌘I